API Specifications & Design

1. API Specifications - Partner Implementation Requirements

The following are the APIs you (the partner anomaly detection service) are required to implement.

Candescent will call these APIs on your service.

1.1 Get Risk Profile API

This API calculates and returns the risk profile for a single banking activity in real-time.

Attribute	Value
API Name	getRiskProfile
URL	`/v1/banking-activity?risk-profile=true`
Method	POST
Content-Type	`application/json`

Request Headers (Sent by Candescent)

Header	Description
`ClientId`	Client identifier issued by you to Candescent
`TransactionId`	Random UUID for request tracking
`Authorization`	`Basic Base64(client_id:client_secret)`
`Content-Type`	`application/json`

Request Body

A single BankingActivity object (see Section 4 for structure).

Response Headers (Your Implementation Must Return)

Header	Description
`TransactionId`	Must echo the request TransactionId

Response Body

A single RiskProfile object (see Section 5 for structure).

Example Request

POST https://your-service.com/v1/banking-activity?risk-profile=true
ClientId: candescent-client-id
TransactionId: 550e8400-e29b-41d4-a716-446655440000
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{
  "activityId": "550e8400-e29b-41d4-a716-446655440000",
  "timeStamp": "2024-12-16T10:30:00Z",
  "activity": "Login",
  "adType": "Transactional",
  "userContext": {
    "channel": "ONLINE",
    "member": "MEM123456",
    "institutionId": "12345",
    "userType": "Retail",
    "ipv4Address": "192.168.1.100",
    "loginName": "john.doe",
    "sessionId": "sess-abc-123",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "Login": {
    "prevBadLoginCount": 0,
    "mfaEnrolled": true,
    "type": "standard"
  }
}

Example Success Response

HTTP/1.1 200 OK
TransactionId: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "activityId": "550e8400-e29b-41d4-a716-446655440000",
  "statusCode": "SUCCESS",
  "statusMessage": "Risk profile evaluated successfully",
  "riskScore": 15.5,
  "riskLevel": "Low",
  "riskAdvice": "Allow",
  "riskFactors": []
}

Example Error Response

HTTP/1.1 400 Bad Request
TransactionId: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "activityId": "550e8400-e29b-41d4-a716-446655440000",
  "statusCode": "ERROR_INVALID_MSG",
  "statusMessage": "Required field 'userContext.institutionId' is missing"
}

1.2 Create Banking Activities API (Bulk)

This API receives a collection of banking activities that load into your database. This feed is used to build and update risk models for real-time risk profile calculations.

Attribute	Value
API Name	createBankingActivities
URL	`/v1/banking-activities`
Method	POST
Content-Type	`application/json`

Request Headers (Sent by Candescent)

Header	Description
`ClientId`	Client identifier issued by you to Candescent
`TransactionId`	Random UUID for request tracking
`Authorization`	`Basic Base64(client_id:client_secret)`
`Content-Type`	`application/json`

Request Body

A BankingActivities object containing a collection of BankingActivity objects.

Response Headers (Your Implementation Must Return)

Header	Description
`TransactionId`	Must echo the request TransactionId

Response Body

A RiskProfiles object containing a collection of RiskProfile objects.

Example Request

POST https://your-service.com/v1/banking-activities
ClientId: candescent-client-id
TransactionId: 660e8400-e29b-41d4-a716-446655440001
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{
  "bankingActivities": [
    {
      "activityId": "550e8400-e29b-41d4-a716-446655440001",
      "timeStamp": "2024-12-16T10:30:00Z",
      "activity": "Login",
      "userContext": {
        "channel": "ONLINE",
        "member": "MEM123456",
        "institutionId": "12345",
        "userType": "Retail",
        "ipv4Address": "192.168.1.100",
        "loginName": "john.doe",
        "sessionId": "sess-abc-123",
        "userAgent": "Mozilla/5.0"
      },
      "Login": {
        "prevBadLoginCount": 0,
        "mfaEnrolled": true
      }
    },
    {
      "activityId": "550e8400-e29b-41d4-a716-446655440002",
      "timeStamp": "2024-12-16T10:31:00Z",
      "activity": "Transfer",
      "userContext": {
        "channel": "ONLINE",
        "member": "MEM123456",
        "institutionId": "12345",
        "userType": "Retail",
        "ipv4Address": "192.168.1.100",
        "loginName": "john.doe",
        "sessionId": "sess-abc-123",
        "userAgent": "Mozilla/5.0"
      },
      "Transfer": {
        "amount": "1000.00",
        "fromAccount": "****1234",
        "toAccount": "****5678",
        "transactionType": "ACH"
      }
    }
  ]
}

Example Success Response

HTTP/1.1 200 OK
TransactionId: 660e8400-e29b-41d4-a716-446655440001
Content-Type: application/json

{
  "riskProfiles": [
    {
      "activityId": "550e8400-e29b-41d4-a716-446655440001",
      "statusCode": "SUCCESS",
      "riskScore": 15.5,
      "riskLevel": "Low",
      "riskAdvice": "Allow"
    },
    {
      "activityId": "550e8400-e29b-41d4-a716-446655440002",
      "statusCode": "SUCCESS",
      "riskScore": 45.0,
      "riskLevel": "Medium",
      "riskAdvice": "Challenge",
      "riskFactors": ["unusual_amount", "new_recipient"]
    }
  ]
}

1.3 Delete User Banking Activities API

This API deletes all data stored in your database for a specific user. This supports compliance requirements and user data management.

Attribute	Value
API Name	deleteUserBankingActivities
URL	`/v1/banking-activities?institutionid={institutionId}&userid={userid}` OR `/v1/banking-activities?institutionid={institutionId}&loginname={loginName}`
Method	DELETE

URL Parameters

Parameter	Required	Description
`institutionId`	Yes	The identifier of the Candescent Digital Banking Financial Institution
`userid`	One Required	The unique identifier of the user (UUID) passed in anomaly detection requests
`loginName`	One Required	The login name of the user passed in anomaly detection requests

Note: Either userid or loginName must be provided, but not both.

Request Headers (Sent by Candescent)

Header	Description
`ClientId`	Client identifier issued by you to Candescent
`TransactionId`	Random UUID for request tracking
`Authorization`	`Basic Base64(client_id:client_secret)`

Request Body

None (N/A)

Response Headers (Your Implementation Must Return)

Header	Description
`TransactionId`	Must echo the request TransactionId

Response Body

A Response object with status code.

Example Request

DELETE https://your-service.com/v1/banking-activities?institutionid=12345&userid=550e8400-e29b-41d4-a716-446655440000
ClientId: candescent-client-id
TransactionId: 770e8400-e29b-41d4-a716-446655440002
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Example Success Response

HTTP/1.1 200 OK
TransactionId: 770e8400-e29b-41d4-a716-446655440002
Content-Type: application/json

{
  "statusCode": "SUCCESS"
}

Example Error Response

HTTP/1.1 400 Bad Request
TransactionId: 770e8400-e29b-41d4-a716-446655440002
Content-Type: application/json

{
  "statusCode": "ERROR_INVALID_USER_ID",
  "statusMessage": "Invalid User Id"
}

2. Request Resource Model

2.1 BankingActivity Object

The BankingActivity resource encapsulates a single banking activity for anomaly detection evaluation. It consists of three sections:

Common metadata This relates to the banking activity
User context This specifies attributes for the user responsible for the activity
Activity payload This is specific to the type of activity

{
  "activityId": "string (UUID, required)",
  "timeStamp": "string (ISO 8601, required)",
  "activity": "string (enum, required)",
  "adType": "string (enum, optional)",
  "adJourneyId": "string (optional)",
  "userContext": "object (required)",
  "<ActivityPayload>": "object (required)"
}

2.2 Common Fields

Field	Type	Required	Description
`activityId`	string (UUID)	Yes	Unique identifier for the API request
`timeStamp`	string (ISO 8601)	Yes	Date and time of the activity
`activity`	string (enum)	Yes	Type of banking activity. For behavioral anomaly detection, this should match the journey name sent to the behavioral anomaly detection service by the UI
`adType`	string (enum)	No	Type of anomaly detection: `Transactional`, `Behavioral`, or `Unknown`. Passed when the client wants to perform specifically behavioral or transactional anomaly detection
`adJourneyId`	string	No	Identifier for behavioral anomaly detection. Generated by the UI and sent to the behavioral anomaly detection service for a specific UI collection

2.3 UserContext Object

{
  "channel": "ONLINE",
  "errorDetail": null,
  "member": "MEM123456",
  "institutionId": "12345",
  "companyId": "987654321",
  "userType": "Retail",
  "userRole": "PRIMARY",
  "ipv4Address": "192.168.1.100",
  "ipv6Address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "locale": "en_US",
  "loginName": "john.doe",
  "sessionId": "sess-abc-123",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "userId": "user-uuid-12345",
  "activityStatus": "Success",
  "userProduct": "Web",
  "subProduct": "RetailBanking",
  "featureName": "AccountTransfer",
  "httpHeaders": { }
}

2.4 UserContext Field Definitions

Field	Type	Required	Description
`channel`	enum	No	Device channel used for digital banking activity (API, EMAIL, MOBILE, ONLINE, etc.)
`errorDetail`	string	No	Error details if the user activity failed
`member`	string	Yes*	Unique identifier of the Financial Institution or End User at the host. Records info for both Retail and Business consumers. *Mandatory except for BadLogin
`institutionId`	string	Yes	Unique 5-digit identifier for the financial institution
`companyId`	string	No	Business banking company ID (9-20 digits). Only logged when userType = BUSINESS
`userType`	enum	Yes*	Retail, Business, or Unknown. *Mandatory except for BadLogin
`userRole`	enum	No	Type of user making the request
`ipv4Address`	string	Yes	IPv4 address of the originator
`ipv6Address`	string	No	IPv6 address of the originator
`locale`	enum	No	User's locale
`loginName`	string	Yes	Login name of the digital banking user
`sessionId`	string	Yes	Unique session identifier for the duration of a user's session. For behavioral anomaly detection, this is used to correlate activities within the same session
`userAgent`	string	Yes	Description of the user's client sent by the browser or device
`userId`	string	No	Unique identifier (UUID) of the digital banking user
`activityStatus`	enum	No	Status of the user activity (Success, Failure, InProcess, InProgress)
`userProduct`	enum	No	Product the user is using when making the banking activity
`subProduct`	string	No	The unique Candescent product name
`featureName`	string	No	Most specific application identifier. Free-form attribute to identify specific features generating actions/events
`httpHeaders`	object	No	HTTP header information

2.5 HttpHeaders Object

Field	Type	Description
`httpAcceptLanguage`	string	Languages the client can understand
`httpAcceptCharsets`	string	Character sets the client can understand
`httpAcceptEncoding`	string	Content encoding (compression) the client can understand
`httpReferer`	string	Address of the previous web page
`httpVia`	string	Proxy information
`httpCookie`	string	HTTP cookies previously sent by the server
`httpAccept`	string	MIME types the client can understand
`httpHost`	string	Domain name of the server
`httpLocation`	string	URL redirect information
`httpForwarded`	string	Client-facing side of proxy server information
`httpXForwardedFor`	string	Originating IP address of client through proxy/load balancer

3. Response Resource Model

3.1 RiskProfile Object

{
  "activityId": "string (UUID)",
  "statusCode": "string (enum)",
  "statusMessage": "string",
  "riskScore": "number (float)",
  "riskLevel": "string (enum)",
  "riskAdvice": "string (enum)",
  "riskFactors": ["string"]
}

3.2 Response Field Definitions

Field	Type	Required	Description
`activityId`	string	Yes	The ID of the original request (used to match requests with responses for async processing)
`statusCode`	enum	Yes	Status code indicating success or error
`statusMessage`	string	No	Human-readable status message
`riskScore`	float	No	Numeric risk score for the user action
`riskLevel`	enum	No	Risk level associated with the user action
`riskAdvice`	enum	No	Recommended risk action if one is configured
`riskFactors`	array	No	List of risk factors associated with the risk advice

3.3 Risk Levels

Level	Description
`VeryLow`	Minimal risk detected
`Low`	Low risk, typical behavior
`Medium`	Moderate risk, may warrant review
`High`	High risk, likely requires action
`VeryHigh`	Very high risk, immediate attention needed
`Other`	Custom risk level
`Unknown`	Unable to determine risk

3.4 Risk Advice

Advice	Description	Expected Candescent Action
`Allow`	Transaction appears legitimate	Proceed normally
`Challenge`	Additional verification needed	Trigger MFA or security questions
`Deny`	High likelihood of fraud	Block the transaction
`Other`	Custom advice	Follow institution-specific rules
`NO RISK ACTION CONFIGURED`	No action configured	Default handling
`Unknown`	Unable to determine	Default handling

3.5 Simple Response Object (for Delete API)

{
  "statusCode": "string (enum)",
  "statusMessage": "string"
}

4. Banking Activity Payloads

The activity payload varies based on the type of activity. Below are examples for common activity types:

{
  "Login": {
    "additionalInfo": {
      "entry": [
        { "key": "deviceFingerprint", "value": "abc123" }
      ]
    },
    "prevBadLoginCount": 0,
    "mfaEnrolled": true,
    "type": "standard"
  }
}

4.2 BadLogin

{
  "BadLogin": {
    "badLoginCount": 3,
    "type": "invalid_password"
  }
}

4.3 Transfer

{
  "Transfer": {
    "action": "create",
    "amount": "1000.00",
    "amountSource": "user_input",
    "confNo": "CONF123456",
    "frequency": "Once",
    "fromAccount": "****1234",
    "fromAccountType": "Checking",
    "fromRoutingNumber": "123456789",
    "memo": "Payment for services",
    "nickname": "Monthly Rent",
    "toAccount": "****5678",
    "toAccountType": "Savings",
    "toRoutingNumber": "987654321",
    "transactionType": "ACH"
  }
}

4.4 ManagePayee

{
  "ManagePayee": {
    "accountNumber": "****1234",
    "accountType": "Checking",
    "action": "add",
    "address1": "123 Main St",
    "city": "New York",
    "currencyCode": "USD",
    "email": "[email protected]",
    "nickname": "Electric Company",
    "payeeName": "City Electric",
    "payeeId": "PAY123",
    "routingNumber": "123456789",
    "state": "NY",
    "zip": 10001,
    "type": "external"
  }
}

4.5 MFAChallenge

{
  "MFAChallenge": {
    "cdiChallenged": true,
    "cdiMode": "active",
    "challengeStatus": "Success",
    "challengeStep": "Challenge Verified",
    "challengeType": "SMS",
    "enrollmentSelected": "Enroll",
    "enrollmentStatus": "Enrolled",
    "invalidAttempts": 0,
    "passcodeSent": true,
    "phoneOrEmail": "***-***-1234",
    "step": "verification"
  }
}

4.6 ZelleTransfer

{
  "ZelleTransfer": {
    "amount": "200.00",
    "fromAccount": "****1234",
    "fromAccountType": "Checking",
    "fromRoutingNumber": "123456789",
    "memo": "Dinner split",
    "nowTransactionId": "ZELLE123456",
    "status": "Posted",
    "toAccount": "[email protected]",
    "transactionType": "send"
  }
}

4.7 ChangePassword

{
  "ChangePassword": {
    "action": "change",
    "destination": "Email Address",
    "trigger": "user_initiated",
    "type": "self_service"
  }
}

4.8 RDCDeposit

{
  "RDCDeposit": {
    "amount": "250.00",
    "checkNumber": "1234",
    "confNo": "RDC987654",
    "depositStatus": "Accepted",
    "status": "Approved",
    "toAccount": "****5678",
    "toAccountType": "Checking"
  }
}

5. Enumerations and Reference Data

5.1 Activity Types

[
  "Login", "Logout", "BadLogin", "Prelogin", "Register", "SingleSignon",
  "MFAChallenge", "MFAChannel", "RegistrationUser", "UsernameChange",
  "UsernameRecovery", "ChangePassword", "ForgottenPassword", "ChangeEmail",
  "ChangePhoneNumber", "ChangePostalAddress", "AlternateCredential",
  "AlternateUserIdRecovery", "Transfer", "ScheduledTransfer", "ZelleTransfer",
  "ManagePayment", "ManagePayee", "SinglePayment", "BPSinglePay",
  "BPAssociateAccount", "ScheduledTransaction", "StopPayment", "ManageRecipient",
  "ManageTemplate", "RDCDeposit", "RDCRegistration", "ManageSubuserPermissions",
  "ManageBusiness", "Accounts", "AccountOpen", "CardManagement",
  "TravelNotification", "TextBankingAccount", "TextBankingActivated",
  "FundingAccount", "CheckImage", "History", "Image", "PFMLogin", "PFMBadLogin"
]

5.2 Channel Types

["API", "EMAIL", "MOBILE", "ONLINE", "PUSH", "SMART_DEVICE", "SMS", "VOICE", "WEARABLE", "UNKNOWN"]

5.3 User Types

["Retail", "Business", "Unknown"]

5.4 User Roles

["BUSINESS_USER", "ENTITLED", "PRIMARY", "PRIMARY_ADMIN", "SECONDARY_ADMIN", "Unknown"]

5.5 User Products

[
  "AdminPlatform", "Alexa", "AmazonBankingApp", "AmazonEchoBankingApp",
  "AmazonTabletBankingApp", "AndroidBankingApp", "AndroidBizBankingApp",
  "AndroidTabBizBankingApp", "AndroidTabletBankingApp", "AndroidWearApp",
  "AppleWatch", "Automation", "iPadBankingApp", "iPadBizBankingApp",
  "iPhoneBankingApp", "iPhoneBizBankingApp", "MMVMobileWeb", "OpenPlatform",
  "SMSBanking", "Popmoney", "Web", "Unknown"
]

5.6 Activity Status

["Success", "Failure", "InProcess", "InProgress", "Unknown"]

5.7 Anomaly Detection Types

["Transactional", "Behavioral", "Unknown"]

5.8 Frequency

[
  "Once", "Onetime", "Weekly", "Monthly", "Quarterly", "SemiAnnually",
  "SemiMonthly", "Annually", "Daily", "BiWeekly", "Every4Months",
  "Every4Weeks", "Every8Weeks", "BiMonthly", "TwiceAMonth", "Unknown"
]

5.9 Challenge Types

["EMAIL", "FI OTP", "OTP", "SMS", "TOKEN", "VOICE", "AUTHENTICATOR", "Unknown"]

5.10 Locale

["en_US", "en_ES", "es_ES", "zh_TW", "Unknown"]

Appendix A: Complete Activity Type Reference

Activity Type	Category	Description
AccountOpen	Account	New account opening
Accounts	Account	Account management
AlternateCredential	Security	Biometric credential setup
AlternateUserIdRecovery	Security	Alternate ID recovery
BadLogin	Authentication	Failed login attempt
BPAssociateAccount	Payment	Bill pay account link
BPSinglePay	Payment	Bill payment
CardManagement	Card	Card actions
ChangeEmail	Profile	Email change
ChangePassword	Security	Password change
ChangePhoneNumber	Profile	Phone change
ChangePostalAddress	Profile	Address change
CheckImage	Account	Check image request
ForgottenPassword	Security	Password reset
FundingAccount	Account	Funding account setup
History	Account	Transaction history
Image	Account	Image retrieval
Login	Authentication	User login
Logout	Authentication	User logout
ManageBusiness	Business	Business management
ManagePayee	Payment	Payee management
ManagePayment	Payment	Payment management
ManageRecipient	Transfer	Recipient management
ManageSubuserPermissions	Business	Permission management
ManageTemplate	Payment	Template management
MFAChallenge	Security	MFA verification
MFAChannel	Security	MFA setup
PFMBadLogin	Authentication	Failed PFM login
PFMLogin	Authentication	PFM login
Prelogin	Authentication	Pre-login check
RDCDeposit	Deposit	Remote deposit
RDCRegistration	Deposit	RDC registration
Register	Authentication	New registration
RegistrationUser	Authentication	User registration
ScheduledTransaction	Transaction	Scheduled transaction
ScheduledTransfer	Transfer	Scheduled transfer
SinglePayment	Payment	One-time payment
SingleSignon	Authentication	SSO login
StopPayment	Payment	Stop payment
TextBankingAccount	Mobile	SMS banking setup
TextBankingActivated	Mobile	SMS banking activation
Transfer	Transfer	Fund transfer
TravelNotification	Card	Travel notice
UsernameChange	Profile	Username change
UsernameRecovery	Security	Username recovery
ZelleTransfer	Transfer	P2P transfer

This document is confidential and proprietary. The information contained herein may not be copied, reproduced, transmitted, or used without the express written consent of Candescent Corporation.

1. API Specifications - Partner Implementation Requirements​

1.1 Get Risk Profile API​

Request Headers (Sent by Candescent)​

Request Body​

Response Headers (Your Implementation Must Return)​

Response Body​

Example Request​

Example Success Response​

Example Error Response​

1.2 Create Banking Activities API (Bulk)​

Request Headers (Sent by Candescent)​

Request Body​

Response Headers (Your Implementation Must Return)​

Response Body​

Example Request​

Example Success Response​

1.3 Delete User Banking Activities API​

URL Parameters​

Request Headers (Sent by Candescent)​

Request Body​

Response Headers (Your Implementation Must Return)​

Response Body​

Example Request​

Example Success Response​

Example Error Response​

2. Request Resource Model​

2.1 BankingActivity Object​

2.2 Common Fields​

2.3 UserContext Object​

2.4 UserContext Field Definitions​

2.5 HttpHeaders Object​

3. Response Resource Model​

3.1 RiskProfile Object​

3.2 Response Field Definitions​

3.3 Risk Levels​

3.4 Risk Advice​

3.5 Simple Response Object (for Delete API)​

4. Banking Activity Payloads​

4.1 Login​

4.2 BadLogin​

4.3 Transfer​

4.4 ManagePayee​

4.5 MFAChallenge​

4.6 ZelleTransfer​

4.7 ChangePassword​

4.8 RDCDeposit​

5. Enumerations and Reference Data​

5.1 Activity Types​

5.2 Channel Types​

5.3 User Types​

5.4 User Roles​

5.5 User Products​

5.6 Activity Status​

5.7 Anomaly Detection Types​

5.8 Frequency​

5.9 Challenge Types​

5.10 Locale​

Appendix A: Complete Activity Type Reference​

1. API Specifications - Partner Implementation Requirements

1.1 Get Risk Profile API

Request Headers (Sent by Candescent)

Request Body

Response Headers (Your Implementation Must Return)

Response Body

Example Request

Example Success Response

Example Error Response

1.2 Create Banking Activities API (Bulk)

Request Headers (Sent by Candescent)

Request Body

Response Headers (Your Implementation Must Return)

Response Body

Example Request

Example Success Response

1.3 Delete User Banking Activities API

URL Parameters

Request Headers (Sent by Candescent)

Request Body

Response Headers (Your Implementation Must Return)

Response Body

Example Request

Example Success Response

Example Error Response

2. Request Resource Model

2.1 BankingActivity Object

2.2 Common Fields

2.3 UserContext Object

2.4 UserContext Field Definitions

2.5 HttpHeaders Object

3. Response Resource Model

3.1 RiskProfile Object

3.2 Response Field Definitions

3.3 Risk Levels

3.4 Risk Advice

3.5 Simple Response Object (for Delete API)

4. Banking Activity Payloads

4.1 Login

4.2 BadLogin

4.3 Transfer

4.4 ManagePayee

4.5 MFAChallenge

4.6 ZelleTransfer

4.7 ChangePassword

4.8 RDCDeposit

5. Enumerations and Reference Data

5.1 Activity Types

5.2 Channel Types

5.3 User Types

5.4 User Roles

5.5 User Products

5.6 Activity Status

5.7 Anomaly Detection Types

5.8 Frequency

5.9 Challenge Types

5.10 Locale

Appendix A: Complete Activity Type Reference